Skip to content

Conversation

@xavdid-stripe
Copy link
Member

@xavdid-stripe xavdid-stripe commented Oct 24, 2025

Why?

We've been designing a streamlined approach to handling incoming events that is easy to get right and hard to get wrong. This PR has the initial implementation of this new system.

NOTE: final names for classes / methods are still being gaveled, so don't worry about those for now. Weigh in on this doc if you have strong feelings there!

The only other pending item is to add a method to allow handling a webhook without verifying the signature. This is good for testing and for Event Bridge, which doesn't use the signature-based verification. Otherwise, this is ready for review.

What?

  • add EventHandler class
  • add event handler constructor on StripeClient
  • add tests

Example usage

client = StripeClient(api_key)
handler = client.router(
    webhook_secret, lambda e, cli, details: print("ignoring unhandled")
)


@handler.on_V1BillingMeterNoMeterFoundEventNotification
def handle_missing_meter(
    notif: V1BillingMeterNoMeterFoundEventNotification, client: StripeClient
):
    event = notif.fetch_event()
    print(f"Err! No meter found: {event.data.developer_message_summary}")


@app.route("/webhook", methods=["POST"])
def webhook():
    webhook_body = request.data
    sig_header = request.headers.get("Stripe-Signature")

    try:
        handler.handle(webhook_body, sig_header)
        return jsonify(success=True), 200
    except Exception as e:
        return jsonify(error=str(e)), 500

See Also

@xavdid-stripe xavdid-stripe changed the title add "inverted" handler add "inverted" event handler Oct 24, 2025
@xavdid-stripe xavdid-stripe changed the base branch from master to beta November 14, 2025 22:20
@xavdid-stripe xavdid-stripe changed the title add "inverted" event handler add event handler class Nov 19, 2025
@xavdid-stripe xavdid-stripe marked this pull request as ready for review November 20, 2025 00:06
@xavdid-stripe xavdid-stripe requested a review from a team as a code owner November 20, 2025 00:06
@xavdid-stripe xavdid-stripe requested review from jar-stripe and removed request for a team and prathmesh-stripe November 20, 2025 00:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants